home *** CD-ROM | disk | FTP | other *** search
/ Amiga Developer CD 2.1 / Amiga Developer CD v2.1.iso / NDK / NDK_3.5 / Documentation / Autodocs / listbrowser_gc.doc < prev    next >
Encoding:
Text File  |  1999-10-30  |  40.9 KB  |  1,123 lines
  1. TABLE OF CONTENTS
  2.  
  3. listbrowser_gc/--datasheet--
  4. listbrowser_gc/LISTBROWSER_GetClass
  5. listbrowser_gc/LBM_ADDNODE
  6. listbrowser_gc/LBM_EDITNODE
  7. listbrowser_gc/LBM_REMNODE
  8. listbrowser_gc/AllocListBrowserNodeA
  9. listbrowser_gc/FreeListBrowserList
  10. listbrowser_gc/FreeListBrowserNode
  11. listbrowser_gc/GetListBrowserNodeAttrsA
  12. listbrowser_gc/HideAllListBrowserChildren
  13. listbrowser_gc/HideListBrowserNodeChildren
  14. listbrowser_gc/ListBrowserSelectAll
  15. listbrowser_gc/SetListBrowserNodeAttrsA
  16. listbrowser_gc/ShowAllListBrowserChildren
  17. listbrowser_gc/ShowListBrowserNodeChildren
  18. listbrowser_gc/--datasheet--                     listbrowser_gc/--datasheet--
  19.  
  20.      NAME
  21.         listbrowser_gc -- For browsing linked lists in various ways.
  22.  
  23.      SUPERCLASS
  24.         gadgetclass
  25.  
  26.      DESCRIPTION
  27.         This gadget is very similar to the LISTVIEW_KIND gadget in
  28.         gadtools.library, with numerous enhancements.  It displays a list in
  29.         a scrolling view so that you can browse through it an select items
  30.         in various ways.
  31.  
  32.         Advantages that this class provides:
  33.  
  34.          > Allows the user to select multiple items (either by dragging or
  35.            shift-key selection).
  36.  
  37.          > Displays items in multiple columns.
  38.  
  39.          > Displays items as a mixture of text and images in different.
  40.            colours.
  41.  
  42.          > Items can have checkboxes that can be toggled on and off.
  43.  
  44.          > Text items can be edited in place.
  45.  
  46.          > Hierarchical display of items supported.
  47.  
  48.          > Can displays column headers.
  49.  
  50.          > Allows allows horizontal scrolling of the list.
  51.  
  52.          > Supports window relativity.
  53.  
  54.          > Supports OS 3.0 BOOPSI Gadget HelpTest.
  55.  
  56.          > Supports layout.gadget/window.class backfills.
  57.  
  58.      METHODS
  59.  
  60.         OM_NEW -- Create the list browser gadget.  Passed to superclass then
  61.             calls OM_SET.
  62.  
  63.         OM_SET -- Set object attributes.  Passed to superclass first.
  64.  
  65.         OM_DISPOSE -- Frees up the list browser gadget.
  66.  
  67.         OM_UPDATE -- Set object notification attributes.  Passed to
  68.             superclass first.
  69.  
  70.         GM_RENDER -- Renders the gadget imagery.  Overrides the superclass.
  71.  
  72.         GM_GOACTIVE -- Handles activation, and selection of the scrollbars
  73.             and arrows.  Overrides the superclass.
  74.  
  75.         GM_HANDLEINPUT -- Handles input events once active.  Overrides the
  76.             superclass.
  77.  
  78.         GM_GOINACTIVE -- Closes the chooser menu.  Overrides the superclass.
  79.  
  80.         LBM_ADDNODE -- Adds a node to the attached list.
  81.  
  82.         LBM_EDITNODE -- Edit an attached nodes attributes.
  83.  
  84.         LBM_REMNODE -- Removes a node from the attached list.
  85.  
  86.         LBM_SORT -- Sort attached list on specified column (V42)
  87.  
  88.         LBM_SHOWCHILDREN --  (V42)
  89.  
  90.         LBM_HIDECHILDREN --  (V42)
  91.  
  92.         All other methods are passed to the superclass.
  93.  
  94.      ATTRIBUTES
  95.         GA_Disabled (BOOL)
  96.             Set to TRUE to disable gadget, FALSE otherwise.
  97.  
  98.             Defaults to FALSE.
  99.  
  100.             Applicability is (OM_NEW, OM_SET, OM_GET)
  101.  
  102.         GA_ReadOnly (BOOL)
  103.             Specifies that the list browser be read-only.  This means that
  104.             no nodes within the list can be selected, the user can just
  105.             scroll through and view the list.  The frame of the list will be
  106.             rendered as recessed as a visual cue that no nodes can be
  107.             selected.
  108.  
  109.             Defaults to FALSE.
  110.  
  111.             Applicability is (OM_NEW, OM_SET, OM_GET)
  112.  
  113.         GA_TextAttr (struct TextAttr *)
  114.             Font to use for the contents of the list browser.
  115.  
  116.             Defaults to the screen's font.
  117.  
  118.             Applicability is (OM_NEW, OM_SET, OM_GET)
  119.  
  120.         LISTBROWSER_Top (LONG)
  121.             Sets the node that is to appear at the top of list browser view.
  122.             Must be positive.  If its beyond the maximum possible value,
  123.             the last page in the list will be displayed.
  124.  
  125.             Defauts to 0.
  126.  
  127.             Applicability is (OM_NEW, OM_SET, OM_GET, OM_NOTIFY)
  128.  
  129.         LISTBROWSER_MakeVisible (LONG)
  130.             Ensures that the specified is within the view and will scroll
  131.             only when necessary (unlike LISTBROWSER_Top which will always
  132.             scrolls).
  133.  
  134.             Defaults to 0.
  135.  
  136.             Applicability is (OM_NEW, OM_SET)
  137.  
  138.         LISTBROWSER_Labels (struct List *)
  139.             An Exec list.  Nodes in this list must be allocated with
  140.             AllocListBrowserNodeA().
  141.  
  142.             A value of ~0 or NULL indicates that the list is "detached".
  143.             This must be done before you can modify a list already attached
  144.             to a list browser. After detaching, you should carry out your
  145.             updates to the list as quickly as possibly and then re-attach.
  146.             When a list browser is initially added to a window it MUST have
  147.             a list attached to it, ~0 is not valid in this case.
  148.  
  149.             If you are using the LISTBROWSER_AutoFit attribute, the column
  150.             sizes will NOT be re-calculated when you change lists, you must
  151.             pass LISTBROWSER_AutoFit, TRUE again to adjust the column sizes
  152.             to fit your new list.
  153.  
  154.             Note that when changing lists, you may want to reset certain
  155.             other attributes, such as LISTBROWSER_Selected, as this value
  156.             will be retained even when changing lists.
  157.  
  158.             NOTE: Lists can NOT be shared amongst other list browsers
  159.             simultaneously.
  160.  
  161.             Applicability is (OM_NEW, OM_SET, OM_GET)
  162.  
  163.         LISTBROWSER_Spacing (WORD)
  164.             If you would like additional spacing between nodes in your
  165.             ListBrowser, use this tag to define how many extra pixels you
  166.             want.
  167.  
  168.             Defaults to 0.
  169.  
  170.             Applicability is (OM_NEW, OM_SET, OM_GET)
  171.  
  172.         LISTBROWSER_Selected (LONG)
  173.             Sets the node in a single-select list that will be selected.
  174.             Any previously selected node(s) will be deselected.  Note
  175.             that a node can become selected without being visible.  A
  176.             value of -1 ( (ULONG)~0 ) is used to say that no item is
  177.             selected.  The results of this tag are undefined in a multi-
  178.             select list browser.
  179.  
  180.             This value is returned in the IntuitMessage.Code field.
  181.  
  182.             Defaults to -1.
  183.  
  184.             Applicability is (OM_NEW, OM_SET, OM_GET, OM_NOTIFY)
  185.  
  186.         LISTBROWSER_SelectedNode (struct Node *)
  187.             This is the same as LISTBROWSER_Selected, except that you refer
  188.             to a node by its actual node structure.
  189.  
  190.             Applicability is (OM_NEW, OM_SET, OM_GET)
  191.  
  192.         LISTBROWSER_MultiSelect (BOOL)
  193.             Puts the list browser into multi-select mode.  In multi-select
  194.             mode the user can select several items from the list by either
  195.             dragging the mouse over items, or holding down the shift key and
  196.             click items to add them to the ones selected.  Nodes can be
  197.             deselected by holding down the shift key and clicking on selected
  198.             node.
  199.  
  200.             Selected nodes will have the LBNA_Selected attribute set to
  201.             TRUE (see GetListBrowserNodeAttrs()).
  202.  
  203.             Defaults to FALSE.
  204.  
  205.             Applicability is (OM_NEW, OM_SET, OM_GET)
  206.  
  207.         LISTBROWSER_PersistSelect (BOOL)
  208.             When the list browser is in multi-select mode, this flag changes
  209.             the selection behaviour so that shift does NOT have to be held
  210.             down to select multiple nodes
  211.  
  212.             Please be aware that this is distinctly NON-STANDARD behaviour
  213.             and therefore should be used with extreme discretion.  About
  214.             the only time this may be appropriate is when you are dealing
  215.             with long lists where users are typically having to select a
  216.             large number of nodes.  Because there is no simple way to clear
  217.             all selections when in this, some method should exist in your
  218.             user interface for clearing all selections.
  219.  
  220.             This has no meaning if the list browser is not in multi-select
  221.             mode.
  222.  
  223.             Defaults to FALSE.
  224.  
  225.             Applicability is (OM_NEW, OM_SET, OM_GET)
  226.  
  227.         LISTBROWSER_ShowSelected (BOOL)
  228.             Specifies that you want the selected item in a single-select
  229.             list browser to be remain visible after it is selected, until
  230.             another item is selected.  This tag has undefined results in
  231.             a multi-select list browser.
  232.         
  233.             Defaults to TRUE.
  234.  
  235.             Applicability is (OM_NEW, OM_SET, OM_GET)
  236.  
  237.         LISTBROWSER_NumSelected (LONG)
  238.             The number of items selected in a multi-select list browser.
  239.             This contains a meaningless value if your listbrowser is not
  240.             multi-select.
  241.  
  242.             Applicability is (OM_GET)
  243.  
  244.         LISTBROWSER_RelEvent (ULONG)
  245.             Describes the event that caused the gadget release of the list
  246.             browser.  Currently defined events are:
  247.  
  248.                 LBRE_NORMAL - Normal selection of an item.
  249.                 LBRE_HIDECHILDREN - The user tried to hide children in a
  250.                     hierarchical listbrowser.
  251.                 LBRE_SHOWCHILDREN - The user tried to show children in a
  252.                     hierarchical listbrowser.
  253.                 LBRE_EDIT - The contents of a node were edited.
  254.                 LBRE_DOUBLECLICK - The node was double-clicked on.
  255.  
  256.                 Additional return values added with V42;
  257.  
  258.                 LBRE_CHECKED - A checkbox node was checked.
  259.                 LBRE_UNCHECKED_ - A checkbox node was unchecked.
  260.                 LBRE_TITLECLICK - A column's title was clicked.
  261.                 LBRE_COLUMNADJUST - A column's separator was clicked/dragged.
  262.  
  263.             Applicability is (OM_GET)
  264.  
  265.         LISTBROWSER_VertSeparators (BOOL)
  266.         LISTBROWSER_Separators (BOOL)
  267.             Specifies that bevelled lines be drawn as separators between
  268.             each column.  Has no effect if the list only has one column.
  269.  
  270.             Defaults to TRUE.
  271.  
  272.             Applicability is (OM_NEW, OM_SET, OM_GET)
  273.  
  274.         LISTBROWSER_HorizSeparators    (BOOL) (V41)
  275.             Renders horizontal lines below each node.  This is useful if your
  276.             listbrowser is very wide, and you want to make it easier for
  277.             users to follow the rows of data.
  278.  
  279.             Defaults to FALSE.
  280.  
  281.             Applicability is (OM_NEW, OM_GET, OM_SET)
  282.  
  283.         LISTBROWSER_Borderless (BOOL)
  284.             Create a view without a border.  Useful if you wish the list
  285.             browser to take up the entire window, and have an attached
  286.             scroller in the window border.
  287.  
  288.             Defaults to FALSE.
  289.  
  290.             Applicability is (OM_NEW, OM_SET, OM_GET)
  291.  
  292.         LISTBROWSER_ColumnInfo (struct ColumnInfo *)
  293.             Provides the column layout info for the list browser.  This is
  294.             an array of struct ColumnInfo.  The array must have one entry
  295.             per column, plus one terminating entry where the ci_Width field
  296.             is -1.  Each field in an array entry is filled in as follows:
  297.  
  298.                 ci_Width (WORD)
  299.                 This specifies the percentage of the view width you want the
  300.                 column to be.  If a virtual width is given, this will be a
  301.                 percentage of that, otherwise it will be a percentage of the
  302.                 actual gadget width.  Since you are specifying a percentage,
  303.                 the actual size of the column will automatically adjust as the
  304.                 virtual or actual width of the gadget changes.
  305.  
  306.                 ci_Title (STRPTR)
  307.                 If you have specified LISTBROWSER_ColumnTitles, TRUE then
  308.                 you MUST fill in the titles you wish to appear for each column
  309.                 here.
  310.  
  311.                 ci_Flags (ULONG)
  312.                 Flags for the column, suported by V42 and later only.
  313.  
  314.                      CIF_WEIGHTED -- weighted width column (default)
  315.                      CIF_FIXED -- fixed pixel width specided in ci_Width.
  316.                      CIF_DRAGGABLE -- separator is user draggable.
  317.                      CIF_NOSEPARATORS -- no separator on this column.
  318.                      CIF_SORTABLE -- column is sortable.
  319.  
  320.             Passing NULL for the ColumnInfo means that you want a single
  321.             column taking up the entire width of the gadget with no title.
  322.  
  323.             NOTES: ColumnInfo can NOT be shared amongst other list browsers
  324.             simultaneously.  While the ColumInfo is in use by list browser,
  325.             you may not modify it.  If you wish to make any modifications
  326.             to it, then first detach the list, make your modifications then
  327.             re-attach the list AND give use LISTBROWSER_ColumnInfo tag
  328.             again.  List browser may modify the contents of this structure.
  329.  
  330.             Defaults to NULL.
  331.  
  332.             Applicability is (OM_NEW, OM_SET, OM_GET)
  333.  
  334.         LISTBROWSER_ColumnTitles (BOOL)
  335.             Show titles above each column.
  336.  
  337.             Defaults to FALSE.
  338.  
  339.             Applicability is (OM_NEW, OM_SET, OM_GET)
  340.  
  341.         LISTBROWSER_AutoFit (BOOL)
  342.             Informs the ListBrowser that you want your column widths
  343.             calculated automatically for you to best fit the items in the
  344.             list attached to it.  This will make your gadget a virtual
  345.             width gadget, with the virtual width being the width needed to
  346.             fit all columns.
  347.  
  348.             For this to work, you must still pass LISTBROWSER_ColumnInfo with
  349.             a ColumInfo structure that has entries for each column, as normal.
  350.             The only change being that the initial values of the ci_Width
  351.             field will be ignored, and instead will be filled in by
  352.             ListBrowser.
  353.  
  354.             If you are using the LISTBROWSER_AutoFit attribute, the column
  355.             sizes will NOT be re-calculated when you change lists with
  356.             LISTBROWSER_Label, you must pass LISTBROWSER_AutoFit, TRUE again
  357.             to adjust the column sizes to fit your new list.
  358.             
  359.             Note for V42, with autofit enabled, wordwrap columns presently
  360.             will NOT rewrap. This is an internal chicken and the egg issue.
  361.  
  362.             Defaults to FALSE.
  363.  
  364.             Applicability is (OM_NEW, OM_SET, OM_GET)
  365.  
  366.         LISTBROWSER_VirtualWidth (WORD)
  367.             Allows rendering beyond the right edge of the view area in the
  368.             gadget.
  369.  
  370.             Defaults to 0.
  371.  
  372.             Applicability is (OM_NEW, OM_SET, OM_GET)
  373.  
  374.         LISTBROWSER_Left (WORD)
  375.             The left offset of the view.  This is only useful in combination
  376.             with either LISTBROWER_VirtualWidth or LISTBROWSER_AutoFit to
  377.             reveal horizontal parts of the view that might be hidden.  The
  378.             offset is specified in terms of pixels.
  379.  
  380.             Defaults to 0.
  381.  
  382.             Applicability is (OM_NEW, OM_SET, OM_GET)
  383.  
  384.         LISTBROWSER_VerticalProp (BOOL)
  385.             Creates a vertical scrollbar with arrows for scrolling up and
  386.             down through the list.
  387.  
  388.             Defaults to TRUE.
  389.  
  390.             Applicability is (OM_NEW, OM_SET, OM_GET)
  391.  
  392.         LISTBROWSER_HorizontalProp (BOOL)
  393.             Creates a horizontal scrollbar with arrows for scrolling
  394.             sideways across the view.  Not useful unless you've used
  395.             LISTBROWSER_VirtualWidth or LISTBROWSER_AutoFit since there
  396.             would be nothing horizontally hidden.
  397.  
  398.             Defaults to FALSE.
  399.  
  400.             Applicability is (OM_NEW, OM_SET, OM_GET)
  401.  
  402.         LISTBROWSER_VPropTotal
  403.         LISTBROWSER_VPropTop
  404.         LISTBROWSER_VPropVisible
  405.         LISTBROWSER_HPropTotal
  406.         LISTBROWSER_HPropTop
  407.         LISTBROWSER_HPropVisible
  408.             These tags are for getting the status of the two prop gadgets
  409.             for the listbrowser.  These are read-only and are intended for
  410.             linking external prop gadgets to a listbrowser.
  411.  
  412.             Applicability is:
  413.             LISTBROWSER_VPropTotal, LISTBROWSER_VPropVisible,
  414.             LISTBROWSER_HPropTotal, LISTBROWSER_HPropVisible:
  415.                 (OM_GET, OM_NOTIFY)
  416.             LISTBROWSER_VPropTop, LISTBROWSER_HPropTop:
  417.                 (OM_SET, OM_GET, OM_NOTIFY)
  418.  
  419.         LISTBROWSER_Position (ULONG)
  420.             Alters the view position within the listbrowser gadget.  See
  421.             the include file for possible positions.  This tag exists mainly
  422.             to make complex keyboard controls simple.
  423.  
  424.             Applicability is (OM_SET)
  425.  
  426.         LISTBROWSER_MouseX (WORD)
  427.         LISTBROWSER_MouseY (WORD)
  428.             Returns the co-ordinates of the mouse within the gadgets box
  429.             when the mouse button was last released in the gadget.
  430.  
  431.             Applicability is (OM_GET)
  432.  
  433.         LISTBROWSER_ScrollRaster (BOOL)
  434.             When this option is set, ListBrowser will use ScrollRaster() for
  435.             extra fast scrolling.  This option is safe to use if the gadget
  436.             will be in a Smart Refresh or Super Bitmap window.
  437.  
  438.             If the gadget will be in a Simple Refresh window, you should be
  439.             aware of an Intuition bug that will cause layer damage to not
  440.             be updated properly.  This problem only exists under V37 of
  441.             Intuition, as ListBrowser sets the GMORE_SCROLLRASTER flag which
  442.             causes proper updates in V39 and above.  HOWEVER, if you are
  443.             using ScrollRaster() in a window that contains a ListBrowser,
  444.             you MUST check the version of Intuition and use
  445.             ScrollWindowRaster() instead if the version is 39 or higher!
  446.  
  447.             Defaults to TRUE.
  448.  
  449.             Applicability is (OM_NEW, OM_GET, OM_SET)
  450.  
  451.         LISTBROWSER_Hierarchical (BOOL)
  452.             Puts the ListBrowser into hierarchical mode, where nodes can be
  453.             browsed in a hierarchically by "generation", and generations can
  454.             be hidden.
  455.  
  456.             See the LBNA_Generation node tag.
  457.  
  458.             Defaults to FALSE.
  459.  
  460.             Applicability is (OM_NEW, OM_GET, OM_SET)
  461.  
  462.         LISTBROWSER_ShowImage (struct Image *)
  463.         LISTBROWSER_HideImage (struct Image *)
  464.         LISTBROWSER_LeafImage (struct Image *)
  465.             You can replace the images for showing a generation, hiding a
  466.             generation and the leaf (no children) image with your own.  If
  467.             you do not provide any of them, default images will be rendered
  468.             for you.
  469.             
  470.             Defaults to NULL.
  471.  
  472.             Applicability is (OM_NEW, OM_GET, OM_SET)
  473.  
  474.         LISTBROWSER_Editable (BOOL)
  475.             If you want to enable in place editing of selected node columns,
  476.             you must set this flag to TRUE.  Note that
  477.             LISTBROWSER_ShowSelected must also be TRUE for node editing to
  478.             work properly.
  479.  
  480.             Defaults to FALSE.
  481.  
  482.             Applicability is (OM_NEW, OM_GET, OM_SET)
  483.  
  484.         LISTBROWSER_EditNode (LONG)
  485.             The number of a node that you want to start editing.  You must
  486.             also specify the column you want to edit with
  487.             LISTBROWSER_EditColumn, and then activate the gadget using
  488.             ActivateGadget() (or ActivateLayoutGadget() if the listbrowser
  489.             is being used with layout.gadget).
  490.  
  491.             This tag will also make the given node the selected node.
  492.  
  493.             Defaults to -1.
  494.  
  495.             Applicability is (OM_NEW, OM_SET)
  496.  
  497.         LISTBROWSER_EditColumn (WORD)
  498.             The number of a column that you want to start editing.  You must
  499.             also specify the node number you want to edit with
  500.             LISTBROWSER_EditNode, and then activate the gadget using
  501.             ActivateGadget() (or ActivateLayoutGadget() if the listbrowser
  502.             is being used with layout.gadget).
  503.  
  504.             Defaults to -1.
  505.  
  506.             Applicability is (OM_NEW, OM_SET)
  507.  
  508.         LISTBROWSER_EditTags (struct TagList *)
  509.             Tags that you want to be passed to the string gadget used when
  510.             editing gadget text.  Though you could theoretically pass any
  511.             tags to the gadget, you should generally not pass tags that
  512.             affect the position of the gadget.
  513.  
  514.             Defaults to NULL.
  515.  
  516.             Applicability is (OM_NEW, OM_GET, OM_SET)
  517.  
  518.         LISTBROWSER_RelColumn (WORD)
  519.             The column the mouse was over when the button is released.  This
  520.             is most useful in a listbrowser with editable nodes in different
  521.             columns.  By checking both this and LISTBROWSER_RelEvent on
  522.             gadget release, you can tell if a node was edited and what column
  523.             of that node was edited.
  524.  
  525.             This  will not contain valid data if the mouse button was
  526.             released over a read-only node or if your listbrowser is in read-
  527.             only mode.
  528.  
  529.             Applicability is (OM_GET)
  530.  
  531.         LISTBROWSER_CheckImage (struct Image *)  (V41)
  532.             Provide a custom image for a checkbox node while that node is
  533.             in the checked state.  A NULL image means that listbrowser
  534.             render some default imagery.
  535.  
  536.             Defaults to NULL.
  537.  
  538.             Applicability is (OM_NEW, OM_GET, OM_SET)
  539.  
  540.         LISTBROWSER_UncheckedImage (struct Image *)  (V41)
  541.             Provide a custom image for a checkbox node while that node is
  542.             in the unchecked state.  A NULL image means that listbrowser
  543.             render some default imagery.
  544.  
  545.             Defaults to NULL.
  546.  
  547.             Applicability is (OM_NEW, OM_GET, OM_SET)
  548.  
  549.         LISTBROWSER_TotalNodes (LONG)  (V41)
  550.             Return the total number of nodes currently attached to the
  551.             listbrowser.
  552.  
  553.             Applicability is (OM_GET)
  554.  
  555.         LISTBROWSER_MinNodeSize (LONG)  (V42)
  556.             Minimum Node size for MemPool optimization, useful when
  557.             coupled with LBNA_NodeSize and using the internal pool.
  558.             
  559.             Applicability is (OM_NEW,OM_SET)
  560.  
  561.         LISTBROWSER_TitleClickable (BOOL)  (V42)
  562.             Enables column-title bar clicking when TRUE.
  563.  
  564.             Defaults to FALSE.
  565.  
  566.             Applicability is (OM_NEW,OM_SET)
  567.  
  568.         LISTBROWSER_MinVisible (LONG)  (V42)
  569.             Minimum visible node count. This is a causes the
  570.             minimum domain to be large enough to hold the specified number
  571.             of nodes using the the estimated average node height.
  572.             Note *ESTIMATED* this is not garanteed results. The result may
  573.             be slightly less or greater than specified, and potentially
  574.             alot greater if other objects within the layout group cause the
  575.             listbrowser to layout larger than its minimum domain.
  576.  
  577.             Applicability is (OM_NEW,OM_SET)
  578.  
  579.         LISTBROWSER_PersistSelect (BOOL)  (V42)
  580.             When set TRUE, SHIFT key is NOT required for multi-select.
  581.  
  582.             Defaults to FALSE.
  583.  
  584.             Applicability is (OM_NEW,OM_SET)
  585.  
  586.         LISTBROWSER_CursorSelect (LOng)  (V42)
  587.             Keyboard cursor selected node number.
  588.  
  589.             Defaults to 0.
  590.  
  591.             Applicability is (OM_SET, OM_GET)
  592.  
  593.         LISTBROWSER_CursorNode (struct Node *)  (V42)
  594.             Keyboard cursor selected node pointer.
  595.  
  596.             Defaults to NULL.
  597.  
  598.             Applicability is (OM_GET)
  599.  
  600.         LISTBROWSER_FastRender (BOOL)  (V42)
  601.             Enables use of mask planes on non-CyberGraphx screens.
  602.             Also turns off custom pen support.
  603.  
  604.             The potential performance improvement with deep ECS or
  605.             AGA displays can be *HUGE* for complex multi-column lists.
  606.             
  607.             Defaults to FALSE.
  608.  
  609.             Applicability is (OM_NET, OM_SET)
  610.  
  611.         LISTBROWSER_TotalVisibleNodes (LONG)  (V42)
  612.             Total visible node count (estimated).
  613.  
  614.             Defaults to 0.
  615.  
  616.             Applicability is (OM_GET)
  617.  
  618.         LISTBROWSER_WrapText (BOOL)  (V42)
  619.             Enables word-wrapping of column nodes flagged for word wrap.
  620.             Wrapping is delimited by a space, '\n' newline, or '\t' tab.
  621.  
  622.             Defaults to 0.
  623.  
  624.             Applicability is (OM_NEW, OM_SET)
  625.  
  626.     BUGS
  627.         Versions 41.250 and below do not support LISTBROWSER_PersistSelect.
  628.         Versions 41.631 and below do not support LISTBROWSER_FastRender correctly.
  629.  
  630.     SEE ALSO
  631.         graphics.library/ScrollRaster(), intuition.library/ActivateGadget(),
  632.         intuition.library/ScrollWindowRaster(), layers.library,
  633.         layout.gadget/ActivateLayoutGadget()
  634. listbrowser_gc/LISTBROWSER_GetClass       listbrowser_gc/LISTBROWSER_GetClass
  635.  
  636.     NAME
  637.         LISTBROWSER_GetClass -- Gets the pointer to the listbrowser class.
  638.  
  639.     SYNOPSIS
  640.         listbrowser_class = LISTBROWSER_GetClass();
  641.         D0
  642.  
  643.         Class * LISTBROWSER_GetClass(VOID);
  644.  
  645.     FUNCTION
  646.         Obtains the pointer to the ListBrowser gadget class for use with
  647.         NewObject().  This function always returns a valid pointer so
  648.         you do not need to check it.  The reason is that if the library
  649.         opens fine, then the pointer returned is already setup.  (Of course
  650.         this implies that if opening the library fails, you shouldn't be
  651.         calling this.)
  652.  
  653.         Note that this function does not create the class, that is done
  654.         when the class library is opened.
  655.  
  656.     INPUTS
  657.         Nothing.
  658.  
  659.     RESULT
  660.         listbrowser_class - Pointer to the ListBrowser gadget class.
  661.  
  662.     SEE ALSO
  663. listbrowser_gc/LBM_ADDNODE                         listbrowser_gc/LBM_ADDNODE
  664.  
  665.     NAME
  666.         LBM_ADDNODE -- Adds a node to the attached list.
  667.  
  668.     FUNCTION
  669.         Allocates a new node and adds it to the list currently attached to
  670.         the listbrowser (if there is one attached).  If rendering
  671.         information is available, then any necessary refreshing will take
  672.         place.  You do not need to detach your list first.
  673.  
  674.         This method takes the following message structure:
  675.  
  676.           struct lbAddNode
  677.           {
  678.               ULONG MethodID;                 /* LBM_ADDNODE */
  679.               struct GadgetInfo *lba_GInfo;   /* to provide rendering info */
  680.               struct Node *lba_Node;          /* Insert() after this node */
  681.               struct TagItem *lba_NodeAttrs;  /* AllocListBrowserNodeA()
  682.                                                  taglist */
  683.           };
  684.  
  685.     RESULT
  686.         Returns a pointer to the allocated node, or NULL on failure.
  687.  
  688.     SEE ALSO
  689.         LBM_EDITNODE, LBM_REMNODE, reaction.lib/LBAddNode
  690. listbrowser_gc/LBM_EDITNODE                       listbrowser_gc/LBM_EDITNODE
  691.  
  692.     NAME
  693.         LBM_EDITNODE -- Edit an attached nodes attributes.
  694.  
  695.     FUNCTION
  696.         Changes attributes of a node attached to a listbrowser.  If rendering
  697.         information is available, then any necessary refreshing will take
  698.         place.  You do not need to detach your list first.
  699.  
  700.         This method takes the following message structure:
  701.  
  702.           struct lbEditNode
  703.           {
  704.               ULONG MethodID;                 /* LBM_EDITNODE */
  705.               struct GadgetInfo *lbe_GInfo;   /* to provide rendering info */
  706.               struct Node *lbe_Node;          /* modify this node */
  707.               struct TagItem *lbe_NodeAttrs;  /* SetListBrowserNodeAttrsA()
  708.                                                  taglist */
  709.           };
  710.  
  711.     RESULT
  712.         Returns non-zero on success, zero on failure.
  713.  
  714.     SEE ALSO
  715.         LBM_ADDNODE, LBM_REMNODE, reaction.lib/LBEditNode
  716. listbrowser_gc/LBM_REMNODE                         listbrowser_gc/LBM_REMNODE
  717.  
  718.     NAME
  719.         LBM_REMNODE -- Removes a node from the attached list.
  720.  
  721.     FUNCTION
  722.         Removes and de-allocates a node from the list currently attached
  723.         to the listbrowser.  If rendering information is available, then
  724.         any necessary refreshing will take place.  You do not need to
  725.         detach your list first.
  726.  
  727.         This method takes the following message structure:
  728.  
  729.           struct lbRemNode
  730.           {
  731.               ULONG MethodID;               /* LBM_REMNODE */
  732.               struct GadgetInfo *lbr_GInfo; /* to provide rendering info */
  733.               struct Node *lbr_Node;        /* Remove() this node */
  734.           };
  735.  
  736.     RESULT
  737.         Returns non-zero on success, zero on failure.
  738.  
  739.     SEE ALSO
  740.         LBM_ADDNODE, LBM_REMNODE, reaction.lib/LBRemNode
  741. listbrowser_gc/AllocListBrowserNodeA     listbrowser_gc/AllocListBrowserNodeA
  742.  
  743.     NAME
  744.         AllocListBrowserNodeA -- Allocate a ListBrowser node.
  745.  
  746.     SYNOPSIS
  747.         struct Node * AllocListBrowserNode(UWORD, Tag, ...)
  748.         node = AllocListBrowserNode(columns, Tag, ...)
  749.  
  750.         struct Node * AllocListBrowserNodeA(UWORD, struct TagItem *)
  751.         node = AllocListBrowserNodeA(columns, taglist)
  752.  
  753.     FUNCTION
  754.         Allocates a node that can be added to the Exec linked list of
  755.         labels in the listbrowser.  This is the only way to allocate a
  756.         node for this list, you cannot allocate nodes yourself because
  757.         the ListBrowser class uses a private node structure.
  758.  
  759.     TAGS
  760.         See SetListBrowserNodeAttrsA() for the list of supported tags.  In
  761.         addition, AllocListBrowserNodeA() supports the following additional
  762.         tags:
  763.  
  764.         LBNA_NodeSize (ULONG) (V41)
  765.         The size in bytes of the public portion of the node structure that
  766.         should be allocated.  Usually the default (sizeof(struct Node)) will
  767.         suffice, unless you wish to have a custom node structure embedded
  768.         within the ListBrowser node, in which case you'd provide the size
  769.         of that structure.  Then the node returned can be treated as an
  770.         instance of your custom node structure.
  771.  
  772.         Defaults to sizeof(struct Node).
  773.  
  774.     INPUTS
  775.         columns - How many columns your ListBrowser has.
  776.         taglist - Attributes for the node, passed onto
  777.             SetListBrowserNodeAttrsA().
  778.  
  779.     RESULT
  780.         node - A node that can be added into the Exec list of labels for
  781.             a ListBrowser gadget.
  782.  
  783.     SEE ALSO
  784.         FreeListBrowserNode(), SetListBrowserNodeAttrsA()
  785. listbrowser_gc/FreeListBrowserList         listbrowser_gc/FreeListBrowserList
  786.  
  787.     NAME
  788.         FreeListBrowserList -- Free a list of ListBrowser nodes.
  789.  
  790.     SYNOPSIS
  791.         VOID FreeListBrowserList(struct List *)
  792.         FreeListBrowserList(List)
  793.  
  794.     FUNCTION
  795.         Frees a list of ListBrowser nodes allocated.
  796.  
  797.     INPUTS
  798.         list - The list of nodes to free.
  799.  
  800.     SEE ALSO
  801.         FreeListBrowserNode()
  802. listbrowser_gc/FreeListBrowserNode         listbrowser_gc/FreeListBrowserNode
  803.  
  804.     NAME
  805.         FreeListBrowserNode -- Free a ListBrowser node.
  806.  
  807.     SYNOPSIS
  808.         VOID FreeListBrowserNode(struct Node *)
  809.         FreeListBrowserNode(node)
  810.  
  811.     FUNCTION
  812.         Frees a ListBrowser node allocated with AllocListBrowserNodeA().
  813.  
  814.     INPUTS
  815.         node - The node to free.
  816.  
  817.     SEE ALSO
  818.         AllocListBrowserNodeA()
  819. listbrowser_gc/GetListBrowserNodeAttrsA listbrowser_gc/GetListBrowserNodeAttrsA
  820.  
  821.     NAME
  822.         GetListBrowserNodeAttrsA -- Get attributes about a ListBrowser node.
  823.  
  824.     SYNOPSIS
  825.         VOID GetListBrowserNodeAttrs(struct Node *, Tag, ...)
  826.         GetListBrowserNodeAttrs(node, firsttag, ...)
  827.  
  828.         VOID GetListBrowserNodeAttrsA(struct Node *, struct TagItem *)
  829.         GetListBrowserNodeAttrsA(node, taglist)
  830.  
  831.     FUNCTION
  832.         The ListBrowser uses a private node structure and all attributes
  833.         are hidden, and must therefore be accessed with this function.
  834.  
  835.     TAGS
  836.         See SetListBrowserNodeAttrsA() for the list of supported tags.
  837.  
  838.     INPUTS
  839.         node - The ListBrowser node to get the information on.
  840.         taglist - A tag list of attributes to get.  ti_Tag is the attribute
  841.             to get and ti_Data is a pointer to a location to copy the result
  842.             to.  The exception is LBNA_Column, which is used to specify a
  843.             column to get attributes on.
  844.  
  845.     SEE ALSO
  846.         SetListBrowserNodeAttrsA()
  847. listbrowser_gc/ListBrowserSelectAll       listbrowser_gc/ListBrowserSelectAll
  848.  
  849.     NAME
  850.         ListBrowserSelectAll -- Select all nodes in a multiselect ListBrowser.
  851.  
  852.     SYNOPSIS
  853.         VOID ListBrowserSelectAll(struct List *);
  854.         ListBrowserSelectAll(list);
  855.  
  856.     FUNCTION
  857.         Sets the LBNA_Selected bit to TRUE in all nodes in list.  This is a
  858.         quick way to select all nodes in a multi-select ListBrowser.
  859.  
  860.         Note that as with any modifications to a ListBrowser list, the list
  861.         MUST be detached to the listbrowser at the time of modification.
  862.  
  863.     INPUTS
  864.         list - a list of ListBrowser nodes, not currently attached to a
  865.             ListBrowser.
  866. listbrowser_gc/HideAllListBrowserChildren listbrowser_gc/HideAllListBrowserChildren
  867.  
  868.     NAME
  869.         HideAllListBrowserChildren -- Hide all children in a ListBrowser.
  870.  
  871.     SYNOPSIS
  872.         VOID HideAllListBrowserChildren(struct List *);
  873.         HideAllListBrowserChildren(list);
  874.  
  875.     FUNCTION
  876.         Hides all children in a hierarchical ListBrowser, "collapsing" all
  877.         generations so that only root generation nodes are shown.
  878.  
  879.         Note that as with any modifications to a ListBrowser list, the list
  880.         MUST be detached to the listbrowser at the time of modification.
  881.  
  882.     INPUTS
  883.         list - a list of ListBrowser nodes, not currently attached to a
  884.             ListBrowser.
  885. listbrowser_gc/HideListBrowserNodeChildren listbrowser_gc/HideListBrowserNodeChildren
  886.  
  887.     NAME
  888.         HideListBrowserNodeChildren -- Hide a ListBrowser node's children
  889.  
  890.     SYNOPSIS
  891.         VOID HideListBrowserNodeChildren(struct Node *);
  892.         HideListBrowserNodeChildren(node);
  893.  
  894.     FUNCTION
  895.         Hides the children of a ListBrowser node.  It will only hide the
  896.         next generation, nodes of higher generations will not be modified.
  897.  
  898.         Note that as with any modifications to a ListBrowser list, the list
  899.         must NOT be detached to the listbrowser at the time of modification.
  900.  
  901.     INPUTS
  902.         node - the node whose children you will be hiding.  The node must
  903.             NOT be in a list that that is currently attached to a ListBrowser.
  904. listbrowser_gc/SetListBrowserNodeAttrsA listbrowser_gc/SetListBrowserNodeAttrsA
  905.  
  906.     NAME
  907.         SetListBrowserNodeAttrsA -- Set attributes of a ListBrowser node.
  908.  
  909.     SYNOPSIS
  910.         VOID SetListBrowserNodeAttrs(struct Node *, Tag, ...)
  911.         SetListBrowserNodeAttrs(node, firsttag, ...)
  912.  
  913.         VOID SetListBrowserNodeAttrsA(struct Node *, struct TagItem *)
  914.         SetListBrowserNodeAttrsA(node, taglist)
  915.  
  916.     FUNCTION
  917.         Changes attributes for a ListBrowser node.  Since the ListBrowser
  918.         class uses a private node structure, this is the only way to change
  919.         node attributes.
  920.  
  921.         You may NOT change node attributes when the node is in a list
  922.         attached to a ListBrowser gadget.  You must first detach the list
  923.         with LISTBROWSER_Labels, ~0 before you can change attributes, and
  924.         then re-attach the list.
  925.  
  926.     TAGS
  927.         LBNA_Selected (BOOL)
  928.  
  929.         If this node is currently selected or not in a multi-select
  930.         list browser.  This field is not meaningful in a single-
  931.         select list browser.
  932.  
  933.         LBNA_Flags (ULONG)
  934.  
  935.         Flags for this node.  See ListBrowser.h for available flags.
  936.  
  937.         LBNA_Generation (WORD)
  938.  
  939.         Sets which "generation" this node belongs to, if the ListBrowser
  940.         is to be in hierarchical mode.  If you were to draw the nodes out
  941.         in a sort of family tree, the generation would refer to the level
  942.         in the tree.
  943.  
  944.         Generations start at 1.  A generation 1 node's children will be
  945.         generation 2, you cannot skip generations.  Nodes need not have
  946.         children and generations can go as deep as you like, limited by
  947.         the available stack of input.device.
  948.  
  949.         LBNA_UserData (APTR)
  950.  
  951.         Abritrary user data for this node.
  952.  
  953.         LBNA_Column (WORD)
  954.  
  955.         A column (from 0 to number_of_columns-1) that the column
  956.         attribute tags below (LBNA_Text, LBNA_Integer, LBNA_FGPen,
  957.         LBNA_BGPen, LBNA_Image, LBNA_SelImage, LBNA_Justification)
  958.         affect.  You typically specify the column to work on, and
  959.         then the column attributes for that column, then the next
  960.         column followed by its attributes, etc.
  961.  
  962.         LBNCA_Text (STRPTR)
  963.  
  964.         Text that is to appear in the corresponding column for
  965.         this node.  Only one of LBNA_Text, LBNA_Integer and
  966.         LBNCA_Image may be non-NULL, specifying the type of contents
  967.         for this column.  Each column of a node need not have the
  968.         same type of contents.  Similarly, the same column in
  969.         different nodes also need not have the same type of contents.
  970.  
  971.         LBNCA_CopyText (BOOL)
  972.  
  973.         Specifies that you want the LBNCA_Text copied to an internal
  974.         buffer by ListBrowser.
  975.  
  976.         LBNCA_Editable (BOOL)
  977.  
  978.         Specifies that this item can be edited.  If the user clicks
  979.         twice on this entry, the text will become a string gadget
  980.         where the user can edit the contents.  This will only work
  981.         if the contents are text (given with LBNCA_Text) AND if
  982.         LBNCA_CopyText was used.  You MUST also specify LBNCA_MaxChars
  983.         to specify how long the edited text can be.
  984.  
  985.         LBNCA_MaxChars(WORD)
  986.  
  987.         Maximum number of characters an editable text entry can be.
  988.  
  989.         LBNCA_Integer (LONG *)
  990.  
  991.         A pointer to an integer to display in this column, or NULL.
  992.  
  993.         LBNCA_FGPen, LBNA_BGPen (WORD)
  994.  
  995.         The pens to be used for rendering the text or integer in
  996.         this column.  Requires that the LBFLG_CUSTOMPENS flag be
  997.         specified, otherwise the default system pens will be used.
  998.  
  999.         LBNCA_Image, LBNA_SelImage (struct Image *)
  1000.  
  1001.         Specifies that the column should contain an image.  The
  1002.         selected image is optional, if not provided, LBNA_Image will
  1003.         be rendered in the IDS_SELECTED state when then node is
  1004.         selected.
  1005.  
  1006.         LBNCA_Justification (WORD)
  1007.  
  1008.         Specifies a justification for the column, either LCJ_LEFT,
  1009.         LCJ_CENTRE or LCJ_RIGHT.
  1010.  
  1011.         LBNA_CheckBox (BOOL) (V41)
  1012.  
  1013.         Means that this node will be a checkbox node, that can be toggled
  1014.         on or off.
  1015.  
  1016.         Defaults to FALSE.
  1017.  
  1018.         LBNA_Checked (BOOL) (V41)
  1019.  
  1020.         Indicates whether a checkbox node is in the checked or unchecked
  1021.         state.
  1022.  
  1023.         Defaults to FALSE.
  1024.  
  1025.         LBNCA_EditTags (struct TagItem *) (V41)
  1026.  
  1027.         Tags that you want to be passed to the string gadget used when
  1028.         editing gadget text.  Though you could theoretically pass any
  1029.         tags to the gadget, you should generally not pass tags that
  1030.         affect the position of the gadget.
  1031.  
  1032.         Defaults to NULL.
  1033.  
  1034.         LBNCA_RenderHook (struct Hook *) (V41)
  1035.  
  1036.         A custom render hook for this node column.  You hook will
  1037.         receive a pointer to struct Node of the node in question as its
  1038.         object, and the following structure in the message pointer:
  1039.  
  1040.           struct LBDrawMsg
  1041.           {
  1042.               ULONG lbdm_MethodID;            /* LV_DRAW */
  1043.               struct RastPort *lbdm_RastPort; /* Where to render to */
  1044.               struct DrawInfo *lbdm_DrawInfo; /* Useful to have around */
  1045.               struct Rectangle lbdm_Bounds;   /* Limits of where to render */
  1046.               ULONG lbdm_State;               /* How to render */
  1047.           };
  1048.  
  1049.         LBDrawMsg.lbdm_State will be either LBR_SELECTED or LBR_NORMAL.  The
  1050.         hook should return LBCB_OK if rendering was successful, or
  1051.         LBCB_UNKNOWN if lbdm_Method doesn't equal LV_DRAW.  No rendering
  1052.         should be performed in this case.
  1053.  
  1054.         Note that this is HIGHLY compatible with a GadTools listhook.
  1055.  
  1056.         Defaults to NULL.
  1057.  
  1058.         LBNCA_HookHeight (WORD) (V41)
  1059.  
  1060.         The height of this column, when using LBNCA_RenderHook.
  1061.  
  1062.         LBNA_MemPool (APTR) (V42)
  1063.  
  1064.         Specifies a custom memory pool to allocate listbrowser nodes from.
  1065.  
  1066.         Defaults to NULL (internal pool).
  1067.         
  1068.         LBNCA_WordWrap (BOOL) (V42)
  1069.         
  1070.         Specifies this column's text can be word wrapped. Useful in
  1071.         weighted column displays or fixed pixels columns. Primarily
  1072.         this feature exists at the request of IRC client authors.
  1073.  
  1074.         Initial implementation in V42.630 is slow. Improvement to be made.
  1075.         
  1076.         Defaults to FALSE.
  1077.  
  1078.     INPUTS
  1079.         node - Node whose attributes you are changing.
  1080.         taglist - Tag list of attributes to change.
  1081.  
  1082.     SEE ALSO
  1083.         GetListBrowserNodeAttrsA()
  1084. listbrowser_gc/ShowAllListBrowserChildren listbrowser_gc/ShowAllListBrowserChildren
  1085.  
  1086.     NAME
  1087.         ShowAllListBrowserChildren -- Show all children in a ListBrowser
  1088.  
  1089.     SYNOPSIS
  1090.         VOID ShowAllListBrowserChildren(struct List *);
  1091.         ShowAllListBrowserChildren(list);
  1092.  
  1093.     FUNCTION
  1094.         Shows all children in a hierarchical ListBrowser, no matter what
  1095.         generation they are in.
  1096.  
  1097.         Note that as with any modifications to a ListBrowser list, the list
  1098.         must NOT be attached to the listbrowser at the time of modification.
  1099.  
  1100.     INPUTS
  1101.         list - a list of ListBrowser nodes, not currently attached to a
  1102.             ListBrowser.
  1103. listbrowser_gc/ShowListBrowserNodeChildren listbrowser_gc/ShowListBrowserNodeChildren
  1104.  
  1105.     NAME
  1106.         ShowListBrowserNodeChildren -- Show children of a ListBrowser node.
  1107.  
  1108.     SYNOPSIS
  1109.         VOID ShowListBrowserNodeChildren(struct Node *, WORD);
  1110.         ShowListBrowserNodeChildren(node, depth);
  1111.  
  1112.     FUNCTION
  1113.         Show the children of a ListBrowser node.  The next depth generations
  1114.         will be shown.  To only show the next generation, use a depth of 1.
  1115.  
  1116.         Note that as with any modifications to a ListBrowser list, the list
  1117.         must NOT be attached to the listbrowser at the time of modification.
  1118.  
  1119.     INPUTS
  1120.         node - the node whose children you will be showing.  The node must
  1121.             NOT be in a list that that is currently attached to a ListBrowser.
  1122.         depth - how many generations deep to show.
  1123.